SndPlay

SndPlay
Header:	Sound.h		Carbon status:	Supported

Plays a sound resource that your application has loaded into memory.

OSErr SndPlay (
    SndChannelPtr chan, 
    SndListHandle sndHandle, 
    Boolean async
);

Parameter descriptions

chan: A pointer to a valid sound channel. You can pass NULL instead of a pointer to a sound channel if you want the Sound Manager to internally allocate a sound channel in your application’s heap zone.
sndHandle: A handle to the sound resource to play.
async: A Boolean value that indicates whether the sound should be played asynchronously (TRUE) or synchronously (FALSE). This parameter is ignored (and the sound plays synchronously) if NULL is passed in the first parameter.

function result: A result code.

DISCUSSION

The SndPlay function attempts to play the sound located at sndHdl, which is expected to have the structure of a format 1 or format 2 'snd ' resource. If the resource has not yet been loaded, the SndPlay function fails and returns the resProblem result code.

All commands and data contained in the sound handle are then sent to the channel. You can pass SndPlay a handle to some data created by calling the Sound Input Manager’s SndRecord function as well as a handle to an actual 'snd ' resource that you have loaded into memory.

In some versions of system software prior to system software version 7.0, the SndPlay function will not work properly with sound resources that specify the sound data type twice. This might happen if a resource specifies that a sound consists of sampled-sound data and an application does the same when creating a sound channel.

The chan parameter is a pointer to a sound channel. If chan is not NULL, it is used as a valid channel. If chan is NULL, an internally allocated sound channel is used. If you do supply a sound channel pointer in the chan parameter, you can play the sound asynchronously. When a sound is played asynchronously, a callback function can be called when a callBackCmd command is processed by the channel. (This function is the callback function supplied to SndNewChannel.) The handle you pass in the sndHdl parameter must be locked for as long as the sound is playing asynchronously.

If a format 1 'snd ' resource does not specify which type of sound data is to be played, SndPlay defaults to square-wave data. SndPlay also supports format 2 'snd ' resources using sampled-sound data and a bufferCmd command. To use SndPlay and sampled-sound data with a format 1 'snd ' resource, the resource must include a bufferCmd command.

The SysBeep and SndPlay functions are the highest-level sound functions that the Sound Manager provides. Depending on the needs of your application, you might be able to accomplish all desired sound-related activity simply by using SysBeep to produce the system alert sound or by using SndPlay to play other sounds that are stored as 'snd ' resources.

SPECIAL CONSIDERATIONS

Because the SndPlay function moves memory, you should not call it at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.